home *** CD-ROM | disk | FTP | other *** search
/ DOpus Plus / DOpus Plus.iso / SDK / docs / edithook.doc < prev    next >
Encoding:
Text File  |  1998-10-26  |  4.4 KB  |  128 lines
  1. dopus5.library/Edit Hook                             dopus5.library/Edit Hook
  2.  
  3.     The dopus5.library provides an edit hook which you can attach to string
  4.     gadgets, to take advantage of some additional features. The features
  5.     provided by the edit hook include :
  6.  
  7.         - Enhanced cursor movement using alt and shift
  8.         - History using up/down cursor
  9.         - Clipboard support (copy, cut and paste)
  10.         - Optional filtering of path characters
  11.         - Secure option where string is not displayed
  12.         - Return automatically activates the next string gadget
  13.         - Key press notification
  14.  
  15.     To use the edit hook in your gadgets, you must obtain a Hook structure
  16.     with the GetEditHook() function. Once you have finished with it, you
  17.     must free this with FreeEditHook().
  18.  
  19. dopus5.library/FreeEditHook                       dopus5.library/FreeEditHook
  20.  
  21.     NAME
  22.         FreeEditHook - free a Hook created with GetEditHook()
  23.  
  24.     SYNOPSIS
  25.         FreeEditHook(hook)
  26.                       A0
  27.  
  28.         void FreeEditHook(struct Hook *);
  29.  
  30.     FUNCTION
  31.         This routine frees a Hook that you obtained via a call to
  32.         GetEditHook().
  33.  
  34.     INPUTS
  35.         hook - hook to free
  36.  
  37.     SEE ALSO
  38.         GetEditHook()
  39.  
  40. dopus5.library/GetEditHook                         dopus5.library/GetEditHook
  41.  
  42.     NAME
  43.         GetEditHook - get a Hook pointer to access the edit hook
  44.  
  45.     SYNOPSIS
  46.         GetEditHook(type, flags, tags)
  47.                      D0     D1    A0
  48.  
  49.         struct Hook *GetEditHook(ULONG, ULONG, struct TagItem *);
  50.  
  51.         struct Hook *GetEditHookTags(ULONG, ULONG, Tag, ...);
  52.  
  53.     FUNCTION
  54.         This routine returns a Hook structure that you can use to give
  55.         the additional capabilities to your string gadgets.
  56.  
  57.     INPUTS
  58.         type - type of Hook (only HOOKTYPE_STANDARD is valid so far)
  59.         flags - a combination of the following flags :
  60.  
  61.                 EDITF_NO_SELECT_NEXT - stops the return key from
  62.                 automatically activating the next (or previous, with shift)
  63.                 string gadget.
  64.  
  65.                 EDITF_PATH_FILTER - filters path characters out of the
  66.                 string (/ and :)
  67.  
  68.                 EDITF_SECURE - secure password field, doesn't display the
  69.                 characters that are typed. If this flag is specified, the
  70.                 gadget's StringInfo->MaxChars value must be twice what
  71.                 it would ordinarily be. The gadget's StringInfo->Buffer
  72.                 must be this size plus an additional two bytes, eg
  73.                 (max_len*2)+2.
  74.  
  75.         tags - the following tags are supported by the edit hook :
  76.  
  77.                EH_History - supplies a pointer to an Att_List structure
  78.                which contains the history list for this gadget. Each entry
  79.                in the list is the name of a node, with the most recent node
  80.                at the end of the list. The Att_List should be created using
  81.                Semaphore locking.
  82.  
  83.                EH_ChangeSigTask - allows you to specify a task that is to be
  84.                signalled whenever the contents of the string gadget are
  85.                changed by the user. This allows you to have a display
  86.                dynamically updated as the user types.
  87.  
  88.                EH_ChangeSigBit - the signal bit used to signal your task.
  89.                This is the bit number, not a mask.
  90.  
  91.     RESULT
  92.         Returns a pointer to a Hook structure which you can use for your
  93.         gadget. It is not a good idea to share hooks between gadgets
  94.         (although unless you are using the EH_History facility it should
  95.         not really be a problem).
  96.  
  97.     SEE ALSO
  98.         FreeEditHook(), GetSecureString(), Att_NewList()
  99.  
  100. dopus5.library/GetSecureString                 dopus5.library/GetSecureString
  101.  
  102.     NAME
  103.         GetSecureString - retrieve the real string from a secure field
  104.  
  105.     SYNOPSIS
  106.         GetSecureString(gadget)
  107.                           A0
  108.  
  109.         char *GetSecureString(struct Gadget *);
  110.  
  111.     FUNCTION
  112.         The secure feature of the edit hook is implemented using a buffer for
  113.         the gadget that is twice as large plus 2 bytes as it would
  114.         ordinarily be. This is because the first half of the buffer is filled
  115.         with * characters as the user types. The real text is stored in the
  116.         second half of the buffer.
  117.  
  118.     INPUTS
  119.         gadget - secure string gadget
  120.  
  121.     RESULT
  122.         Returns a pointer to the real text for the gadget. The text is
  123.         properly null-terminated.
  124.  
  125.     SEE ALSO
  126.         GetEditHook()
  127.  
  128.